home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kbookmark.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  10.5 KB  |  330 lines
  1. // -*- c-basic-offset: 4; indent-tabs-mode:nil -*-
  2. // vim: set ts=4 sts=4 sw=4 et:
  3. /* This file is part of the KDE libraries
  4.    Copyright (C) 2000 David Faure <faure@kde.org>
  5.  
  6.    This library is free software; you can redistribute it and/or
  7.    modify it under the terms of the GNU Library General Public
  8.    License version 2 as published by the Free Software Foundation.
  9.  
  10.    This library is distributed in the hope that it will be useful,
  11.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.    Library General Public License for more details.
  14.  
  15.    You should have received a copy of the GNU Library General Public License
  16.    along with this library; see the file COPYING.LIB.  If not, write to
  17.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18.    Boston, MA 02110-1301, USA.
  19. */
  20. #ifndef __kbookmark_h
  21. #define __kbookmark_h
  22.  
  23. #include <qstring.h>
  24. #include <qvaluelist.h>
  25. #include <qdom.h>
  26. #include <kurl.h>
  27.  
  28. class KBookmarkManager;
  29. class KBookmarkGroup;
  30.  
  31. class KIO_EXPORT KBookmark
  32. {
  33.     friend class KBookmarkGroup;
  34. public:
  35.     enum MetaDataOverwriteMode {
  36.         OverwriteMetaData, DontOverwriteMetaData
  37.     };
  38.  
  39.     KBookmark( ) {}
  40.     KBookmark( QDomElement elem ) : element(elem) {}
  41.  
  42.     static KBookmark standaloneBookmark( const QString & text, const KURL & url, const QString & icon = QString::null );
  43.  
  44.     /**
  45.      * Whether the bookmark is a group or a normal bookmark
  46.      */
  47.     bool isGroup() const;
  48.  
  49.     /**
  50.      * Whether the bookmark is a separator
  51.      */
  52.     bool isSeparator() const;
  53.  
  54.     /**
  55.      * @return true if this is a null bookmark. This will never
  56.      * be the case for a real bookmark (in a menu), but it's used
  57.      * for instance as the end condition for KBookmarkGroup::next()
  58.      */
  59.     bool isNull() const {return element.isNull();}
  60.  
  61.     /**
  62.      * @return true if bookmark is contained by a QDomDocument,
  63.      * if not it is most likely that it has become separated and
  64.      * is thus invalid and/or has been deleted from the bookmarks.
  65.      * @since 3.2
  66.      */
  67.     bool hasParent() const;
  68.  
  69.     /**
  70.      * Text shown for the bookmark
  71.      * If bigger than 40, the text is shortened by
  72.      * replacing middle characters with "..." (see KStringHandler::csqueeze)
  73.      */
  74.     QString text() const;
  75.     /**
  76.      * Text shown for the bookmark, not truncated.
  77.      * You should not use this - this is mainly for keditbookmarks.
  78.      */
  79.     QString fullText() const;
  80.     /**
  81.      * URL contained by the bookmark
  82.      */
  83.     KURL url() const;
  84.     /**
  85.      * @return the pixmap file for this bookmark
  86.      * (i.e. the name of the icon)
  87.      */
  88.     QString icon() const;
  89.  
  90.     /**
  91.      * @return the group containing this bookmark
  92.      */
  93.     KBookmarkGroup parentGroup() const;
  94.  
  95.     /**
  96.      * Convert this to a group - do this only if
  97.      * isGroup() returns true.
  98.      */
  99.     KBookmarkGroup toGroup() const;
  100.  
  101.     /**
  102.      * Return the "address" of this bookmark in the whole tree.
  103.      * This is used when telling other processes about a change
  104.      * in a given bookmark. The encoding of the address is "/4/2", for
  105.      * instance, to design the 2nd child inside the 4th child of the root bk.
  106.      */
  107.     QString address() const;
  108.  
  109.     // Hard to decide. Good design would imply that each bookmark
  110.     // knows about its manager, so that there can be several managers.
  111.     // But if we say there is only one manager (i.e. set of bookmarks)
  112.     // per application, then KBookmarkManager::self() is much easier.
  113.     //KBookmarkManager * manager() const { return m_manager; }
  114.  
  115.     /**
  116.      * @internal for KEditBookmarks
  117.      */
  118.     QDomElement internalElement() const { return element; }
  119.  
  120.     /**
  121.      * Updates the bookmarks access metadata
  122.      * Call when a user accesses the bookmark
  123.      * @since 3.2
  124.      */
  125.     void updateAccessMetadata();
  126.  
  127.     // Utility functions (internal)
  128.  
  129.     /**
  130.      * @return address of parent
  131.      */
  132.     static QString parentAddress( const QString & address )
  133.     { return address.left( address.findRev('/') ); }
  134.  
  135.     /**
  136.      * @return position in parent (e.g. /4/5/2 -> 2)
  137.      */
  138.     static uint positionInParent( const QString & address )
  139.     { return address.mid( address.findRev('/') + 1 ).toInt(); }
  140.  
  141.     /**
  142.      * @return address of previous sibling (e.g. /4/5/2 -> /4/5/1)
  143.      * Returns QString::null for a first child
  144.      */
  145.     static QString previousAddress( const QString & address )
  146.     {
  147.         uint pp = positionInParent(address);
  148.         return pp>0 ? parentAddress(address) + '/' + QString::number(pp-1) : QString::null;
  149.     }
  150.  
  151.     /**
  152.      * @return address of next sibling (e.g. /4/5/2 -> /4/5/3)
  153.      * This doesn't check whether it actually exists
  154.      */
  155.     static QString nextAddress( const QString & address )
  156.     { return parentAddress(address) + '/' + QString::number(positionInParent(address)+1); }
  157.  
  158.     /**
  159.      * @return the common parent of both addresses which 
  160.      * has the greatest depth
  161.      * @since 3.5
  162.      */
  163.      static QString commonParent(QString A, QString B);
  164.  
  165.     /**
  166.      * Get the value of a specific metadata item.
  167.      * @param key Name of the metadata item
  168.      * @return Value of the metadata item. QString::null is returned in case
  169.      * the specified key does not exist.
  170.      * @since 3.4
  171.      */
  172.     QString metaDataItem( const QString &key ) const;
  173.  
  174.     /**
  175.      * Change the value of a specific metadata item, or create the given item
  176.      * if it doesn't exist already.
  177.      * @param key Name of the metadata item to change
  178.      * @param value Value to use for the specified metadata item
  179.      * @param mode Whether to overwrite the item's value if it exists already or not.
  180.      * @since 3.4
  181.      */
  182.     void setMetaDataItem( const QString &key, const QString &value, MetaDataOverwriteMode mode = OverwriteMetaData );
  183.  
  184. protected:
  185.     QDomElement element;
  186.     // Note: you can't add new member variables here.
  187.     // The KBookmarks are created on the fly, as wrappers
  188.     // around internal QDomElements. Any additional information
  189.     // has to be implemented as an attribute of the QDomElement.
  190.  
  191. private:
  192.     bool hasMetaData() const;
  193.     static QString left(const QString & str, uint len);
  194. };
  195.  
  196. /**
  197.  * A group of bookmarks
  198.  */
  199. class KIO_EXPORT KBookmarkGroup : public KBookmark
  200. {
  201. public:
  202.     /**
  203.      * Create an invalid group. This is mostly for use in QValueList,
  204.      * and other places where we need a null group.
  205.      * Also used as a parent for a bookmark that doesn't have one
  206.      * (e.g. Netscape bookmarks)
  207.      */
  208.     KBookmarkGroup();
  209.  
  210.     /**
  211.      * Create a bookmark group as specified by the given element
  212.      */
  213.     KBookmarkGroup( QDomElement elem );
  214.  
  215.     /**
  216.      * Much like KBookmark::address, but caches the
  217.      * address into m_address.
  218.      */
  219.     QString groupAddress() const;
  220.  
  221.     /**
  222.      * @return true if the bookmark folder is opened in the bookmark editor
  223.      */
  224.     bool isOpen() const;
  225.  
  226.     /**
  227.      * Return the first child bookmark of this group
  228.      */
  229.     KBookmark first() const;
  230.     /**
  231.      * Return the prevous sibling of a child bookmark of this group
  232.      * @param current has to be one of our child bookmarks.
  233.      */
  234.     KBookmark previous( const KBookmark & current ) const;
  235.     /**
  236.      * Return the next sibling of a child bookmark of this group
  237.      * @param current has to be one of our child bookmarks.
  238.      */
  239.     KBookmark next( const KBookmark & current ) const;
  240.  
  241.     /**
  242.      * Create a new bookmark folder, as the last child of this group
  243.      * @param mgr the manager of the bookmark
  244.      * @param text for the folder. If empty, the user will be queried for it.
  245.      * @param emitSignal if true emit KBookmarkNotifier signal
  246.      */
  247.     KBookmarkGroup createNewFolder( KBookmarkManager* mgr, const QString & text = QString::null, bool emitSignal = true );
  248.     /**
  249.      * Create a new bookmark separator
  250.      * Don't forget to use KBookmarkManager::self()->emitChanged( parentBookmark );
  251.      */
  252.     KBookmark createNewSeparator();
  253.  
  254.     /**
  255.      * Create a new bookmark, as the last child of this group
  256.      * Don't forget to use KBookmarkManager::self()->emitChanged( parentBookmark );
  257.      * @param mgr the manager of the bookmark
  258.      * @param bm the bookmark to add
  259.      * @param emitSignal if true emit KBookmarkNotifier signal
  260.      * @since 3.4
  261.      */
  262.     KBookmark addBookmark( KBookmarkManager* mgr, const KBookmark &bm, bool emitSignal = true );
  263.  
  264.     /**
  265.      * Create a new bookmark, as the last child of this group
  266.      * Don't forget to use KBookmarkManager::self()->emitChanged( parentBookmark );
  267.      * @param mgr the manager of the bookmark
  268.      * @param text for the bookmark
  269.      * @param url the URL that the bookmark points to
  270.      * @param icon the name of the icon to associate with the bookmark. A suitable default
  271.      * will be determined from the URL if not specified.
  272.      * @param emitSignal if true emit KBookmarkNotifier signal
  273.      */
  274.     KBookmark addBookmark( KBookmarkManager* mgr, const QString & text, const KURL & url, const QString & icon = QString::null, bool emitSignal = true );
  275.  
  276.     /**
  277.      * Moves @p item after @p after (which should be a child of ours).
  278.      * If item is null, @p item is moved as the first child.
  279.      * Don't forget to use KBookmarkManager::self()->emitChanged( parentBookmark );
  280.      */
  281.     bool moveItem( const KBookmark & item, const KBookmark & after );
  282.  
  283.     /**
  284.      * Delete a bookmark - it has to be one of our children !
  285.      * Don't forget to use KBookmarkManager::self()->emitChanged( parentBookmark );
  286.      */
  287.     void deleteBookmark( KBookmark bk );
  288.  
  289.     /**
  290.      * @return true if this is the toolbar group
  291.      */
  292.     bool isToolbarGroup() const;
  293.     /**
  294.      * @internal
  295.      */
  296.     QDomElement findToolbar() const;
  297.  
  298.     /**
  299.      * @return the list of urls of bookmarks at top level of the group
  300.      * @since 3.2
  301.      */
  302.     QValueList<KURL> groupUrlList() const;
  303.  
  304. protected:
  305.     QDomElement nextKnownTag( QDomElement start, bool goNext ) const;
  306.  
  307. private:
  308.     mutable QString m_address;
  309.     // Note: you can't add other member variables here, except for caching info.
  310.     // The KBookmarks are created on the fly, as wrappers
  311.     // around internal QDomElements. Any additional information
  312.     // has to be implemented as an attribute of the QDomElement.
  313. };
  314.  
  315. /**
  316.  * @since 3.2
  317.  */
  318. class KIO_EXPORT KBookmarkGroupTraverser {
  319. protected:
  320.     virtual ~KBookmarkGroupTraverser() { ; }
  321.     void traverse(const KBookmarkGroup &);
  322.     virtual void visit(const KBookmark &) { ; }
  323.     virtual void visitEnter(const KBookmarkGroup &) { ; }
  324.     virtual void visitLeave(const KBookmarkGroup &) { ; }
  325. private:
  326.     class KBookmarkGroupTraverserPrivate *d;
  327. };
  328.  
  329. #endif
  330.